Software Documentation or Source Code Documentation is written text that accompanies computer software and is often created in a computer development environment. Generally, such documentation explains how the underlying code operates and/or how to utilize the code. The term software documentation can have more than one context and thus exist in different forms. Some example types of documentation include architecture or design documentation for software. Another form includes technical documentation of code, algorithms, interfaces, and APIs. Still yet other forms of documentation include manuals for the end-user, system administrators, support staff along with marketing literature including product briefs and promotional information.
Design documents tend to take a broad view. Rather than describe how things are used, this type of documentation focuses more on the why. For example, in a design document, a programmer may explain the rationale behind organizing a data structure in a particular manner, or may list member functions of a particular object and how to add new objects to the code. This may include explaining the reasons why a given class is constructed in a particular manner, outlining patterns, discussing alternative designs, outlining ideas for improvement, or providing plans for how to improve designs later on such as with respect to future projects. This type of documentation is typically not considered appropriate for code or technical documentation however that is designed with other requirements in mind.
Regarding technical documentation, this is the type of information most programmers think of when using the term software documentation. When creating software, code alone is insufficient. There should be some text along with the code to describe various aspects of its intended operation. This documentation is usually embedded within the source code itself so it is readily accessible to anyone who may be traversing though it. In one instance, comments may be added to source code that can be highly technical and are mainly employed to define and explain APIs, data structures and algorithms. For example, one might use this documentation to explain that a variable refers to a particular location or machine in a factory. It is important for code documents to be thorough, but not so verbose that it becomes difficult to maintain. In addition to source code documentation, other technical documentation requirements may include descriptions on tasks, routines, controllers, modules, data types, tags, phases, add-on instructions, and so forth.
Often, tools such as Doxygen, javadoc, ROBODoc, POD or TwinText can be used to auto-generate code documents—that is, they extract comments from the source code and create reference manuals in such forms as text or HTML files. Code documents are often organized into a reference guide style, allowing programmers to quickly look up an arbitrary function or class. Many programmers are comfortable with the notion of auto-generating documentation for various reasons. For example, since it is extracted from the source code itself (for example, through comments), the programmer can write it while referring to their code, and can thus employ the same tools used to create the source code, to generate the documentation.
In addition to standard documentation tasks, systems are now developed for markets across the global economy. Thus, not only is documentation required in the native language employed for code or system development, there often is a requirement to have the documentation localized into one or more foreign languages in addition to the language the original code was developed in. As development of software projects continues to become more global, users have a need to deploy software or system designs across the world where the language of the consumers of the respective design may be different than the language of the creators of the design. Thus, different languages may be spoken by the development engineer, the maintenance engineer, and the operators that view the design which can create problems for those who may need to update, alter, and/or operate the given design.
Another problem with current documentation schemes is that it may not be possible to easily associate certain control system documentation with a specified “spoken language” for example machine names or numeric constants. Also, different types of documentation may be desired for different user-types of a given project. For instance, a designer may document their code with long and short forms of the project documentation in the same spoken language, a maintainer may desire to view a shortened-version of project documentation out on the plant floor, whereas a troubleshooter may desire to view a longer-form version of project documentation to help get to the root of potential issues.